XCurl 概述

本主题介绍 xCurl 库，该库是符合 libCurl API 的 Microsoft 游戏开发工具包 （GDK） 实现。 建议将 xCurl作为 Microsoft 游戏开发工具包 （GDK） 的 HTTP API 游戏。 xCurl 通过遵守所有安全要求和最佳做法来简化游戏开发，而不需要任何特殊的游戏逻辑或处理。 但是，它不支持 WebSocket 通信。 如果需要实现 WebSocket 通信，请改用 libHttpClient。

xCurl 不同于 libCurl ，因为 xCurl 是在 WinHttp 之上实现的，并自动遵循所有额外的 Microsoft 游戏开发工具包 （GDK） 要求和最佳做法。 因此，虽然 libCurl 本身不满足 Microsoft Game Core 主机平台的安全要求，但 xCurl 使你可跨所有平台维持相同的 libCurl HTTP 实现，同时只更改一个标头 include 和库链接。

xCurl中未实现多个libCurl API，因为它们不符合 Microsoft 游戏开发工具包 （GDK） 游戏的安全要求。 本主题稍后介绍区别。 xCurl 依赖于游戏运行时，并且在 XGameRuntimeInitialize 之后才能被调用。

要了解 xCurl 方法的工作原理，请参阅 libCurl API 文档。

备注

xCurl 和 WinHttp 是 Xbox 主机上 HTTP 的唯一安全选项。 xCurl WinHttp 实现适用于 Windows 电脑 和 Xbox 主机，无需更改代码。 但是，在 Windows 电脑上，可以直接将 libCurl 或任何其他 HTTP 堆栈与 Microsoft 游戏开发工具包 （GDK） 游戏一起使用。

若要在Windows 10电脑或 Xbox 主机上的 Microsoft 游戏开发工具包 （GDK） 游戏中使用 xCurl ，请在项目中包括 xCurl 扩展 SDK 标头和库。

确保已在开发电脑上安装了游戏运行时开发包 (GRDK)。

打开游戏的 .vcxproj 文件并添加以下元素。 这将会链接导入库，并将 XCurl.dll 包含在生成输出中。

xCurl 具有不同的标头，可将自身与 libCurl 区分开来。 在游戏中要包含 curl.h 的位置，需要用 xcurl.h 替换标头，如下所示。

xCurl 相当于用以下内部版本标志编译的 libCurl。

xCurl 自动处理网络初始化。 可以在游戏生命周期的任何时期设置和执行请求。 任何在网络初始化前开始的请求都会延迟并排队，直到网络初始化；通过这种方式，XCurl 确保请求会在尽可能早的时间发出，而不需要游戏进行任何额外处理。

xCurl 自动处理暂停和恢复。 暂停时，所有未完成的请求将立即取消，并以 CURLE_NO_CONNECTION_AVAILABLE 方式失败。 此外，在这些请求上为 CURLINFO_OS_ERRNO 查询 curl_easy_getinfo 将像其他 GRTS API 一样返回 HRESULT_FROM_WIN32(PROCESS_SUSPEND_RESUME)，以防想以不同于一般网络断开故障的方式处理这些故障。

所有的 xCurl 图柄在整个游戏生命周期内都保持有效，包括在暂停/恢复的界限内。 在暂停/恢复时不需要清理或初始化任何 xCurl 图柄。 任何在暂停后开始的新请求将推迟直到恢复以及随后的网络初始化，以确保它们将尽快启动，而不需要游戏进行任何额外的处理。

备注

将多接口用于 xCurl时，当存在未完成的请求时，游戏应继续调用 curl_multi_perform 以及 curl_multi_poll 或 curl_multi_wait 挂起。 xCurl 将阻止暂停，直到所有正在进行的请求完成，如果不调用 curl_multi_perform 可能导致游戏在暂停期间超时。 建议不管暂停/恢复状态如何，在整个生命周期中都持续调用 curl_multi_perform。 xCurl 在内部处理暂停状态的所有复杂问题。

xCurl 在内部处理 XR-12 游戏的所有方面，所有通过 xCurl 的 HTTPS 请求都自动符合 XR-12 标准。

xCurl 自动执行通过游戏“单一登录门户”指定的任何特殊证书固定。

在开发套件上，可以指定未加密的 HTTP 方案、http://，用于调试流量和测试目的。 对于所有 RETAIL 请求，必须指定 HTTPS 方案、https://，以符合 XR-12 兼容。 未明确指定方案的 XCurl 请求将推断 HTTPS 方案。

备注

xCurl 不执行自动令牌插入。 若要检索 Xbox Live 令牌，游戏应该调用 XUserGetTokenAndSignatureAsync 或 XUserGetTokenAndSignatureUtf16Async 的GRTS API 来检索授权和签名标头，然后在调用 curl_easy_setopt 时使用 CURLOPT_HEADER、CURLOPT_HTTPHEADER 或 CURLOPT_HEADERFUNCTION 选项，以在提出请求前设置标头。

xCurl 与适用于 WinHttp 的并发请求限制相同。 游戏应将并发请求限制为不超过 8 个，以确保所有呼叫正常运行。 此并发限制适用于从 xCurl、WinHttp 和 Xbox 服务 API 中的任何一个发出的并发请求。

xCurl 使用翻转缓冲器来接收数据。 这允许它在向读取回调提供完整缓冲区的同时开始填充第二个缓冲区，然后在填充第一个缓冲区时切换到向读取回调提供第二个缓冲区。 然而，如果读取回调的时间太长，或者在多模式下 curl_multi_perform 的调用不够频繁，WinSock 的内核内存可能会积累起来。 有关 WinSock 内核内存的详细信息，请参阅 套接字内存注意事项。

默认情况下，xCurl 使用 Windows 堆并可通过 XMemSetWin32HeapTrackingHooks 追踪其分配。 或者，初始化时可提供内存函数，例如 libCurl。

除了 curl_global_init_mem，xCurl 还提供了可选的 xCurl_global_init_mem。 提供给此版本的 init 的回调与其他 Microsoft 游戏开发工具包 （GDK） 内存回调类似，提供的信息比标准 libCurl 有关所分配数据的回调更多。

xCurl 中的 easy 句柄支持以下选项：

xCurl 不公开用于传输的基础套接字。 因此， xCurl 没有实现任何用于套接字操作的选项和 API。 这也消除了使用 fd_sets 来等待数据通过 select 和 poll 到达的能力。 要等待到达，请使用 curl_multi_wait 和 curl_multi_poll。

以下 API 不存在于 xCurl

以下选项均无效。

该 CURL Share 界面未实现。

目前不支持此功能。 从回调中返回 CURL_WRITEFUNC_PAUSE 或 CURL_READFUNC_PAUSE 会导致无法恢复的中止操作。

libCurl API

在合作伙伴中心设置 Web 服务（NDA 主题）

Xbox One 主机上的 Fiddler